feat(abstract-utxo): add Pearl fixed-script wallet surface by manojkumar138 · Pull Request #9360 · BitGo/BitGoJS

manojkumar138 · 2026-07-27T09:58:58Z

Summary

Adds the Pearl (Duplex) fixed-script wallet surface to abstract-utxo, plus the sdk-coin-pearl registration shim. Follows #9347, which defined the coin in statics.

No utxo-lib changes — Pearl is served entirely through @bitgo/wasm-utxo. Per @OttoAllmendinger: no descriptors, no ordinals, no utxo-core, no utxo-bin.

PR 2 of 3. coinFactory / bitgo module wiring follows in PR 3 (CECHO-1792).

Changes

File	Change
`abstract-utxo/src/names.ts`	`pearl` / `tpearl` registered; `Pearl` added to `getBaseNameFromMainnet`
`abstract-utxo/src/impl/pearl/`	new — `Pearl` / `Tpearl` classes
`abstract-utxo/src/impl/index.ts`, `src/index.ts`	export the new impl
`sdk-coin-pearl/`	new package — re-export + `register()` shim
`tsconfig.packages.json`	register the new package
`sdk-core/.../abstractUtxoCoinUtil.ts`	actionable error for coins with no utxo-lib network
6 × `package.json` + `yarn.lock`	`@bitgo/wasm-utxo` `^4.21.1` → `^4.27.0`

The coin classes are ~15 lines each, mirroring impl/ltc/.

Taproot-only comes for free

The TDD sketched a getSupportedScriptTypes() override. It isn't needed — AbstractUtxoCoin.supportsAddressType() already delegates to wasm:

supportsAddressType(addressType: ScriptType2Of3): boolean {
  return fixedScriptWallet.supportsScriptType(this.name, addressType);
}

and wasm-utxo 4.27.0 reports only the taproot types for Pearl. Verified — abstract-utxo's p2tr spelling resolves correctly against wasm's p2trLegacy:

pearl p2sh -> false    p2shP2wsh -> false    p2wsh -> false
pearl p2tr -> true     p2trMusig2 -> true

supportsAddressChain() inherits this, so chains 30/31/40/41 are supported and 0/1/10/11/20/21 are not. Both are pinned in the new test rather than left implicit, so a regression in either layer is caught.

Why all six wasm-utxo bumps

Bumping abstract-utxo alone left two ranges in play, and yarn resolved two copies of the wasm binary — 4.27.0 nested under abstract-utxo, 4.21.1 hoisted at the root. Aligning all six collapses it to a single hoisted 4.27.0. The lockfile diff is one entry.

This is a dependency-hygiene change, not Pearl support being added to utxo-core / utxo-bin — no code in those packages changed.

`sdk-core` — deliberately not fully fixed

getUtxoCoinScriptTypes2Of3() and getUtxoCoinScriptTypesForWalletType() resolve statics' utxolibName into a utxo-lib network:

const network = utxolib.networks[coin.network.utxolibName as utxolib.NetworkName];

For Pearl that is undefined, and the code then threw a bare TypeError: invalid network. It now throws:

coin pearl has no utxo-lib network (utxolibName=pearl).
Script types for wasm-only coins must be resolved through @bitgo/wasm-utxo.

I stopped there rather than routing these through wasm, because sdk-core does not depend on @bitgo/wasm-utxo and adding a WASM binary to a core package is an architectural decision with bundle-size consequences for every consumer — not mine to make in this PR. There are no in-repo callers; both functions are public API consumed by wallet-platform / bitgo-ui. @OttoAllmendinger this is the spot that matters for WP onboarding — happy to take whichever direction you prefer (wasm dep in sdk-core, a lookup table, or handling it WP-side).

Test coverage

New abstract-utxo/test/unit/impl/pearl/unit/index.ts (7 tests), following the impl/btg convention: instantiation, chain, full name, testnet inheritance, taproot-only script types, taproot-only address chains, and an explicit assertion that no utxo-lib network exists for Pearl — no other checked-in coin has that profile, so it can't be inferred from an existing coin.

Pearl is deliberately not added to the shared utxoCoins fixtures. That infrastructure maps coin names to utxo-lib networks (getNetworkForCoinName throws for unknown coins, and getUtxoCoins() sorts by utxolib.getNetworkList() position), so Pearl has nothing to point at. Adding it would have meant reworking test infra shared by 17 suites, 8 of which resolve a utxolib network. The dedicated suite covers what this PR actually adds.

RecoveryProvider.forCoin is also left without a Pearl case — Blockchair has no Pearl support, and the existing fallthrough already throws ApiNotImplementedError, which is the correct outcome rather than a silent wrong provider.

Verification

Module	Result
`abstract-utxo`	1552 passing (1545 → +7)
`sdk-core`	530 passing
`statics`	32269 passing
`utxo-core`	239 passing
`utxo-bin`	237 passing
`utxo-descriptors`	35 passing
`utxo-ord`	173 passing
`utxo-staking`	59 passing

Zero failures. abstract-utxo, sdk-coin-pearl, sdk-core, and all five wasm dependents build clean. Prettier clean; eslint clean (0 errors). Verified end-to-end that sdk-coin-pearl re-exports both classes and register is callable, and that getFullNameFromCoinName yields Pearl / Testnet Pearl.

CI status: blocked only on npm package creation

Everything substantive is green. The single real failure is verify-npm-packages, with all-checks failing downstream of it:

Check	Result
`unit-test` (20.x / 22.x / 24.x)	✅ pass
`code-quality` (lint / format / dependencies / commit-lint)	✅ pass
`docker-build`	✅ pass
`verify-npm-packages`	❌ fail
`all-checks`	❌ fail (aggregate — fails only because of the above)

These packages must be created on npm before publishing with trusted publishing.

1 package(s) not found on npm:

  - @bitgo/sdk-coin-pearl (modules/sdk-coin-pearl)

This is a prerequisite for any new package rather than something fixable in the diff: .github/actions/verify-npm-packages requires every non-private package to already exist on the registry, because npm trusted publishing needs the package created and its publisher configured up front.

Confirmed both scopes are missing, not just the one CI reports:

@bitgo/sdk-coin-pearl       -> NOT FOUND
@bitgo-beta/sdk-coin-pearl  -> NOT FOUND

# control
@bitgo/sdk-coin-btc         -> 2.13.27
@bitgo-beta/sdk-coin-btc    -> 1.0.1

Raised VL-7329 (assigned to @andyfischer-bitgo, Velocity / BitGoJS Trusted publishing) to create both packages and configure GHA as trusted publisher — same request as VL-6005 for sdk-coin-starknet. No change to this PR is needed once that lands; the check should pass on a re-run.

The alternative would be marking the package "private": true to force the gate green, but that makes it unpublishable and would leave PR 3's wiring pointing at something consumers can't install — so I'd rather wait for the npm setup than hide it.

pranishnepal

1 package(s) not found on npm:

  - @bitgo/sdk-coin-pearl (modules/sdk-coin-pearl)

CI's red and drafted - unsubscribing

OttoAllmendinger

lgtm but check CI errors

manojkumar138 · 2026-07-28T03:26:25Z

@claude review

github-actions · 2026-07-28T03:26:50Z

Claude finished @manojkumar138's task —— View job

Pearl (Duplex) Implementation Review ✅

Todo List:

Read and analyze the Pearl implementation files
Review the abstract-utxo integration
Check test coverage and quality
Verify wasm-utxo version bumps
Review sdk-core error handling changes
Provide comprehensive review feedback

Overall Assessment: APPROVED ✅

This is a well-implemented, clean addition that follows BitGoJS patterns correctly. The implementation is minimal and focused, following the established LTC pattern while properly handling Pearl's unique wasm-only nature.

✅ Strengths

Architecture & Design

Perfect pattern adherence: Pearl/Tpearl classes mirror the LTC implementation exactly (modules/abstract-utxo/src/impl/ltc/)
Minimal surface area: Classes are appropriately simple (~15-21 lines each) with clear inheritance
Wasm-first approach: Correctly delegates script type support to @bitgo/wasm-utxo without utxo-lib dependency
Clean separation: sdk-coin-pearl package provides proper re-export + registration shim

Integration Quality

Names registration: Properly added pearl/tpearl to utxoCoinsMainnet/utxoCoinsTestnet arrays
Type safety: UtxoCoinName types updated correctly
Export chain: Clean exports through impl/index.ts → src/index.ts → sdk-coin-pearl
Full name mapping: getBaseNameFromMainnet correctly returns "Pearl"

Test Coverage

Comprehensive suite: 7 focused tests covering instantiation, chains, names, inheritance, and script types
Taproot verification: Explicitly tests that only p2tr/p2trMusig2 are supported (chains 30/31/40/41)
Regression protection: Tests explicitly verify NO utxo-lib network exists - unique to Pearl
Address chain testing: Verifies both supported (30/31/40/41) and unsupported (0/1/10/11/20/21) chains

Error Handling Enhancement

Actionable errors: sdk-core now throws helpful error messages for wasm-only coins:

coin pearl has no utxo-lib network (utxolibName=pearl).
Script types for wasm-only coins must be resolved through @bitgo/wasm-utxo.

Test coverage: New tests verify the improved error messages work correctly

Dependency Management

Single wasm-utxo version: Bumping all 6 packages from ^4.21.1 to ^4.27.0 prevents duplicate binaries
Dependency hygiene: Ensures single hoisted copy instead of nested duplicates
Minimal scope: Only version bumps, no code changes in utxo-core/utxo-bin

🔍 Minor Observations

Documentation

Excellent PR description: Clear rationale for each change, verification results, and architectural decisions
Code comments: Pearl class has good inline documentation explaining taproot-only nature
README: sdk-coin-pearl README follows package conventions

CI Status

Expected failure: verify-npm-packages failure is expected - npm packages need to be created first
All tests pass: 1552 abstract-utxo tests (1545→+7), all other modules green
Code quality: Lint, format, and commit-lint all pass

Package Structure

Standard layout: sdk-coin-pearl follows established package conventions (tsconfig, .mocharc, etc.)
Proper exports: ESM/CJS dual build setup matches other sdk-coin packages

📋 Verification Checklist

✅ Follows LTC implementation pattern exactly
✅ Proper abstract-utxo integration without utxo-lib dependency
✅ Taproot-only behavior correctly implemented through wasm delegation
✅ Complete test coverage with explicit regression protection
✅ Clean dependency management with unified wasm-utxo version
✅ Proper error handling for wasm-only coins
✅ Standard package structure and exports
✅ Type safety and naming consistency

🎯 Recommendation

Ready to merge once VL-7329 creates the npm packages. The implementation is solid, well-tested, and follows all BitGoJS conventions. No code changes needed.

The architectural decision to keep sdk-core wasm-free is sound - routing these functions through wasm would have bundle-size implications for all consumers.

Review completed for commit f341484

Copilot

Pull request overview

Adds Pearl (and testnet Pearl) as wasm-only, fixed-script UTXO coin implementations in @bitgo/abstract-utxo, provides an @bitgo/sdk-coin-pearl registration shim, and aligns @bitgo/wasm-utxo dependency versions across UTXO-related modules to avoid duplicate WASM installs.

Changes:

Register pearl / tpearl coin names in abstract-utxo, add minimal Pearl / Tpearl coin classes, and export them from the module surface.
Add sdk-coin-pearl package that re-exports the coin classes and provides a register() helper for SDK registration.
Improve sdk-core error messaging when a statics UTXO coin has no @bitgo/utxo-lib network (wasm-only coins), and add test coverage for the new behavior.
Bump @bitgo/wasm-utxo from ^4.21.1 to ^4.27.0 across affected packages and lockfile.

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
yarn.lock	Locks `@bitgo/wasm-utxo` to `4.27.0`.
tsconfig.packages.json	Adds `modules/sdk-coin-pearl` to TS project references.
modules/utxo-staking/package.json	Bumps `@bitgo/wasm-utxo` dependency.
modules/utxo-ord/package.json	Bumps `@bitgo/wasm-utxo` dependency.
modules/utxo-descriptors/package.json	Bumps `@bitgo/wasm-utxo` dependency.
modules/utxo-core/package.json	Bumps `@bitgo/wasm-utxo` dependency.
modules/utxo-bin/package.json	Bumps `@bitgo/wasm-utxo` dependency.
modules/sdk-core/test/unit/bitgo/utils/abstractUtxoCoinUtil.ts	Adds test for actionable error message for wasm-only coins.
modules/sdk-core/src/bitgo/utils/abstractUtxoCoinUtil.ts	Introduces `getUtxolibNetwork()` helper and throws actionable error when network is missing.
modules/sdk-coin-pearl/tsconfig.json	Adds CJS build config for new package.
modules/sdk-coin-pearl/tsconfig.esm.json	Adds ESM build config for new package.
modules/sdk-coin-pearl/src/index.ts	Re-exports `Pearl`/`Tpearl` and adds `register()` shim.
modules/sdk-coin-pearl/README.md	Documents usage and wasm-only/utxo-lib absence.
modules/sdk-coin-pearl/package.json	Defines new package metadata, build scripts, and exports map.
modules/sdk-coin-pearl/.prettierrc.yml	Adds Prettier config for the new package.
modules/sdk-coin-pearl/.prettierignore	Adds Prettier ignore entries for build artifacts.
modules/sdk-coin-pearl/.npmignore	Controls npm publish contents.
modules/sdk-coin-pearl/.mocharc.yml	Adds mocha config (even though tests are delegated elsewhere).
modules/sdk-coin-pearl/.gitignore	Ignores build output and local artifacts.
modules/sdk-coin-pearl/.eslintignore	Ignores build output and local artifacts for linting.
modules/abstract-utxo/test/unit/impl/pearl/unit/index.ts	Adds unit tests for Pearl behavior (taproot-only, chain support, no utxo-lib network).
modules/abstract-utxo/src/names.ts	Registers `pearl` / `tpearl` names and base-name mapping.
modules/abstract-utxo/src/index.ts	Exports Pearl implementation from module entrypoint.
modules/abstract-utxo/src/impl/pearl/pearl.ts	Adds `Pearl` coin class (wasm-only).
modules/abstract-utxo/src/impl/pearl/tpearl.ts	Adds `Tpearl` coin class.
modules/abstract-utxo/src/impl/pearl/index.ts	Barrel export for Pearl implementation.
modules/abstract-utxo/src/impl/index.ts	Exposes pearl impl namespace.
modules/abstract-utxo/package.json	Bumps `@bitgo/wasm-utxo` dependency.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add the Pearl (Duplex) coin classes to abstract-utxo and the sdk-coin-pearl registration shim, following PR 1 which defined the coin in statics. Pearl is served entirely through @bitgo/wasm-utxo and has no @bitgo/utxo-lib network registration, so no utxo-lib changes are needed here. Taproot-only support needs no override. supportsAddressType already delegates to fixedScriptWallet.supportsScriptType, which reports only p2tr and p2trMusig2 for this coin, and supportsAddressChain inherits that. The new test pins the behaviour so a regression in either layer is caught. Bump @bitgo/wasm-utxo to ^4.27.0, the first release carrying pearl and tpearl in CoinName. All six utxo packages are bumped together rather than abstract-utxo alone: mixed ranges made yarn resolve two copies of the wasm binary, one hoisted and one nested. sdk-core's getUtxoCoinScriptTypes2Of3 and getUtxoCoinScriptTypesForWalletType resolve statics' utxolibName into a utxo-lib network, which does not exist for Pearl. They now fail with an actionable message pointing at wasm-utxo instead of a bare `TypeError: invalid network`. Resolving those two through wasm is left for the wallet-platform work, since sdk-core does not depend on wasm-utxo today. Pearl is deliberately left out of the shared utxoCoins test fixtures: that infrastructure maps coin names to utxo-lib networks, which Pearl does not have. Coverage lives in the dedicated impl/pearl suite instead. Recovery via RecoveryProvider.forCoin is also left unimplemented for Pearl - Blockchair has no Pearl support, and the existing default throws ApiNotImplementedError. TICKET: CECHO-1791 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

manojkumar138 · 2026-07-28T03:38:47Z

Addressed the review feedback in 64662cf466. Also noting the npm blocker is now resolved.

Copilot's comment — fixed, plus a pre-existing bug

The ask was to assert the new error behaviour for getUtxoCoinScriptTypesForWalletType, not just the 2-of-3 variant. Fair — that function resolves the network twice (once via getUtxoCoinScriptTypes2Of3, once directly for isEnabledAddressType), so a partial fix could pass one and not the other. Added, covering pearl/tpearl × hot/cold.

Doing it surfaced something separate: that entire describe block was calling getUtxoCoinScriptTypes2Of3, not the wallet-type function — which wasn't even imported. walletType was accepted and ignored, so the hot/cold pairs asserted identical things. I rewired the block to its actual subject and added a test pinning the real wallet-type rule (p2trMusig2 hot-only on mainnet, allowed for cold on testnet), which previously had no coverage. Called out explicitly since it changes pre-existing test behaviour; all original assertions still pass.

sdk-core: 530 → 532 passing. abstract-utxo unchanged at 1552. Prettier and eslint clean.

Claude's review — no changes needed

Verdict was "Ready to merge... No code changes needed", and it independently endorsed keeping sdk-core wasm-free as "sound — routing these functions through wasm would have bundle-size implications for all consumers." That matches Otto's service-first WP design, where service-only coins never dereference coin.network at all, so the tripwire behaviour is the desired end state rather than a stopgap.

Blocker resolved

VL-7329 is done — both packages now exist:

@bitgo/sdk-coin-pearl       -> 0.0.1
@bitgo-beta/sdk-coin-pearl  -> 0.0.1

verify-npm-packages passes. I also checked the declared "version": "1.0.0" against precedent — sdk-coin-starknet (the analogous new package from VL-6005) also declared 1.0.0 on first commit, so this matches convention; the 0.0.1 on npm is just the reservation stub and lerna's independent mode takes it from there. No change needed.

Given the unblock, the revert of PR 1 (#9362) is no longer needed and has been closed.

Copilot

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated no new comments.

Wire the Pearl (Duplex) coin classes from @bitgo/sdk-coin-pearl into the bitgo module so `bitgo.coin('pearl')` and `bitgo.coin('tpearl')` resolve. Completes the BitGoJS onboarding started in #9347 (statics) and #9360 (abstract-utxo + sdk-coin-pearl). Registers in both mechanisms: registerCoinConstructors for eager registration and getCoinConstructor for the lazy lookup. Pearl and Tpearl are imported directly from @bitgo/sdk-coin-pearl rather than through the ./coins barrel. Routing them through the barrel makes coinFactory observe a partially initialised module and leaves unrelated constructors such as TethLikeCoin undefined at registration time. Several other coins in this file are imported directly for the same reason. The barrel still re-exports Pearl/Tpearl so `import { Pearl } from 'bitgo'` keeps working like every other coin. Regenerate the Dockerfile with `yarn update-dockerfile` so the new module is copied and linked for bitgo-express. This is generated content and the dockerfile-check CI job diffs it, so it must be committed rather than hand-edited. TICKET: CECHO-1792 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

manojkumar138 requested review from a team as code owners July 27, 2026 09:58

manojkumar138 requested review from Charan-Ratlan and OttoAllmendinger July 27, 2026 09:59

manojkumar138 marked this pull request as draft July 27, 2026 11:01

manojkumar138 mentioned this pull request Jul 27, 2026

Revert "feat(statics): add Pearl to statics" #9362

Closed

pranishnepal reviewed Jul 27, 2026

View reviewed changes

OttoAllmendinger reviewed Jul 27, 2026

View reviewed changes

manojkumar138 marked this pull request as ready for review July 28, 2026 03:20

manojkumar138 requested review from OttoAllmendinger and pranishnepal July 28, 2026 03:21

davidkaplanbitgo previously approved these changes Jul 28, 2026

View reviewed changes

manojkumar138 requested a review from Copilot July 28, 2026 03:26

Copilot started reviewing on behalf of manojkumar138 July 28, 2026 03:26 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

Comment thread modules/sdk-core/test/unit/bitgo/utils/abstractUtxoCoinUtil.ts

manojkumar138 dismissed davidkaplanbitgo’s stale review via 64662cf July 28, 2026 03:38

manojkumar138 force-pushed the CECHO-1791-add-pearl-to-abstract-utxo branch from f341484 to 64662cf Compare July 28, 2026 03:38

manojkumar138 requested a review from Copilot July 28, 2026 03:39

Copilot started reviewing on behalf of manojkumar138 July 28, 2026 03:39 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

davidkaplanbitgo approved these changes Jul 28, 2026

View reviewed changes

manojkumar138 merged commit 9ceb87e into master Jul 28, 2026
27 checks passed

manojkumar138 mentioned this pull request Jul 28, 2026

feat(bitgo): register Pearl in the coin factory #9366

Merged

manojkumar138 mentioned this pull request Jul 28, 2026

test(abstract-utxo): Pearl transaction flow and live-node cross-validation #9367

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(abstract-utxo): add Pearl fixed-script wallet surface - #9360

feat(abstract-utxo): add Pearl fixed-script wallet surface#9360
manojkumar138 merged 1 commit into
masterfrom
CECHO-1791-add-pearl-to-abstract-utxo

manojkumar138 commented Jul 27, 2026

Uh oh!

linear-code Bot commented Jul 27, 2026

Uh oh!

manojkumar138 commented Jul 27, 2026

Uh oh!

pranishnepal left a comment

Uh oh!

OttoAllmendinger left a comment

Uh oh!

manojkumar138 commented Jul 28, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

manojkumar138 commented Jul 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

manojkumar138 commented Jul 27, 2026

Summary

Changes

Taproot-only comes for free

Why all six wasm-utxo bumps

sdk-core — deliberately not fully fixed

Test coverage

Verification

Related

Uh oh!

linear-code Bot commented Jul 27, 2026

Uh oh!

manojkumar138 commented Jul 27, 2026

CI status: blocked only on npm package creation

Uh oh!

pranishnepal left a comment

Choose a reason for hiding this comment

Uh oh!

OttoAllmendinger left a comment

Choose a reason for hiding this comment

Uh oh!

manojkumar138 commented Jul 28, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pearl (Duplex) Implementation Review ✅

Overall Assessment: APPROVED ✅

✅ Strengths

Architecture & Design

Integration Quality

Test Coverage

Error Handling Enhancement

Dependency Management

🔍 Minor Observations

Documentation

CI Status

Package Structure

📋 Verification Checklist

🎯 Recommendation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

manojkumar138 commented Jul 28, 2026

Copilot's comment — fixed, plus a pre-existing bug

Claude's review — no changes needed

Blocker resolved

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

`sdk-core` — deliberately not fully fixed

github-actions Bot commented Jul 28, 2026 •

edited

Loading